Add publishing & signing docs; generate Android App Bundle #342

paulproteus · 2020-04-08T02:46:34Z

Fixes #438.

I'd love your feedback on this. I know there's more changes I need to make, but I wanted to get a draft out ASAP.

Some questions for you:

Is it organized in the way you'd expect?
Did I miss any TODOs? :)
Where do we ask the user to store their Android app signing keys? We could use ~/.briefcase/keys/ by default in these instructions. I get the impression there is no true consistent default keystore path in Android; the official docs use an arbitrary-seeming path: https://developer.android.com/studio/publish/app-signing#generate-key . Whatever path we decide on, I'm going to have to make sure these docs use it consistently, so I left it a TODO until we chat.

I'll proofread it at least once before resubmitting to you.

paulproteus · 2020-04-08T05:10:41Z

filename:

~/.briefcase/android-app-keys.jks

The alias should be the reverse dotted name of the app.

paulproteus · 2020-04-08T05:18:24Z

I'll try to migrate this to use Google's hosted signing thing, which means our key would become an "uploading" key in their terminology.

freakboy3742

Not sure if the Play Store has had a major update since you wrote this, but the workflow I saw didn't match what you wrote here (definitely enough to get me going, but plenty of discrepancies.)

freakboy3742 · 2020-06-14T01:37:08Z

docs/how-to/code-signing/android.rst

+
+Run this command::
+
+  $ keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias


Some guidance on appropriate naming schemes for "my release key" and "my-alias" would be helpful. Are these keystores/keys app specific? project specific? Organization specific?

Fixed now, I believe.

freakboy3742 · 2020-06-14T01:37:41Z

docs/how-to/publishing/android.rst

+
+::
+
+  $ zipalign -p 4 -f filename.apk


Need to describe where these tools are located on the path.

This overwrites the exsitng file; would it be safer to give instructions that result in an "app-release-aligned.apk"?

FWIW, the reason I wrote it this way is that zipalign is a very safe operation IMHO, so adding another file creates more confusion than it's worth.

Having said that, the zipalign process is no longer needed with the Android App Bundle approach, so whatever. :)

Fixed now, I believe.

freakboy3742 · 2020-06-14T01:45:30Z

docs/how-to/publishing/android.rst

+Adding the app requires a few steps. You need to have a Google Account and
+create a listing for your app. You will need to choose your app's signing
+configuration in the store. Finally, you will create a new release of the app,
+at which point you will upload the APK files that comprise your app.


Worth mentioning the registration fee (A$25; don't know what is in US monies)

Fixed now, I believe.

freakboy3742 · 2020-06-14T01:48:12Z

docs/how-to/publishing/android.rst

+
+Once you've done that, click **Create Application**. Choose a language and
+write a brief app title, up to 50 characters. This should probably be the
+same as your app's Formal Name in the BeeWare ecosystem.


Don't know if this has changed since you wrote this, but I'm seeing "Publish an Android App on Google Play"

I was really confused by this difference. The reason is that I already had one Google Play Store Android app in my Google Play Store console, whereas you didn't. Presumably our users will be more like you than like me in this regard. I'll be fixing that now :)

Fixed now, I believe.

freakboy3742 · 2020-06-14T02:02:45Z

docs/how-to/publishing/android.rst

+your app's ``pyproject.toml`` file. Look for a line starting with ``icon = ``.
+The Google Play Store will require a variety of other information, including at least
+one screenshot of your app and your assessment of likelihood that children will want
+to use the app.


Icon needs to be 512x512, which isn't a size required during setup.

Minium 2 screenshots are required; they must be at least 320px, no more than 3480px, and can't have an aspect ratio > 2:1.

Feature graphic (1024x500px) is also required.

Other details like a promo graphic, tv banner, promo vidio, and daydream 360 degree stereoscopic image can be provided, but aren't required.

Fixed now, I believe.

freakboy3742 · 2020-06-14T02:03:44Z

docs/how-to/publishing/android.rst

+
+Click **App Signing** in the left navigation. The Google Play Store offers an app signing
+feature where they maintain the signing key for your app. For simplicity, you will
+click **Opt Out** to opt out of that feature.


This appears out of order; I couldn't manage keys until uploading an APK.

Fixed now, I believe.

freakboy3742 · 2020-06-14T02:12:58Z

docs/how-to/publishing/android.rst

+  app's signing key.
+
+  You can enable this feature later if you are willing to give Google the private
+  key corresponding to this app.


From going through the release process, it's pretty clear that Google wants you to use google-managed keysigning. I'd argue it's better for these instructions to reflect that.

+1; fixed now, I believe.

freakboy3742 · 2020-06-14T02:14:46Z

docs/how-to/publishing/android.rst

+
+This will prompt a variety of questions from the Google Play Store about the content
+of your app, including the absence/presence of advertising, its appropriateness for
+different age groups, and any embedded commercial aspects.


I also had to save a draft, then visit the "Content Rating", "App Content" and "Pricing and Distribution" tabs to fill out all sorts of details. There's a series of grayed out arrows; until they're all green, you can't publish. There wasn't a "just answer the questions" workflow.

It also raised a warning about being a non-optimized bundle. Short term, we need to flag this isn't a problem; long term, we should modify the publish command to produce multiple APKs.

Fixed now. (Also, the Android App Bundle saves us from the non-optimized bundle problem! Yay.)

freakboy3742 · 2020-06-14T02:33:07Z

docs/how-to/publishing/android.rst

+same as your app's Formal Name in the BeeWare ecosystem.
+
+This will take you to **Store Listing** section of your app. You will need to
+answer a variety of questions. Take your time to answer them well.


"Your app metadata may be helpful here."

paulproteus · 2020-06-14T03:43:34Z

Hi @freakboy3742 -- good feedback. I'll plan to take a fresh look and submit revisions tomorrow daytime my time, perhaps sooner.

…and-publishing-docs-android

…ommand)

paulproteus · 2020-06-27T00:24:15Z

Hi @freakboy3742 -- I've tested this pretty well and am happy for another review pass and/or merge if you like. Note that the switch to Android App Bundle format results in a change in the code and docs.

freakboy3742

A couple of initial review comments; more to come later.

freakboy3742 · 2020-06-27T00:48:23Z

docs/how-to/publishing/android.rst

+
+    .. code-block:: bash
+
+      $ ~/.briefcase/tools/java/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks android/*/app/build/outputs/bundle/release/app-release.aab upload-key -storepass android


To confirm - the '*' here is trying to capturie "all .aab files in the android folder" without explicitly naming the app, right? The possible problem here is that a briefcase project can contain multiple apps.

Also - does this sign-in-place, or produce a new aab file somewhere?

To confirm - the '*' here is trying to capturie "all .aab files in the android folder" without explicitly naming the app, right? The possible problem here is that a briefcase project can contain multiple apps.

True -- I'm trying to capture "all .aab files in the android folder". And true -- this is a bad fit given the possibility of a briefcase project containing multiple apps. I hadn't considered that.

I'll fix that in a follow-up push in a sec.

Also - does this sign-in-place, or produce a new aab file somewhere?

In-place.

freakboy3742 · 2020-06-27T00:48:41Z

docs/how-to/code-signing/android.rst

+We use a password of **android**. This is the `default password for common
+Android keystores <https://developers.google.com/android/guides/client-auth>`__.
+You can change the password if you like. It is more important to limit who
+has access to the keystore file than to change the password.


Any reference on “use the default password" as best practice? The general philosophy makes sense, but if we're going to recommend using a default password, I want to be sure we're giving good advice.

Unfortunately, no -- this page here talks about creating and confirming a secure password for your keystore -- https://developer.android.com/studio/publish/app-signing -- followed by a different password for the key.

This is IMHO near-total insanity.

A Java keystore does nearly nothing, and the Java keystore password is approximately useless. See https://gist.github.com/zach-klippenstein/4631307 for demo code that shows how to change the password on a keystore without knowing the old password.

In our case, I'm using the PKCS #12 format for keystores, which may or may not have that specific problem, but it adds no value to the key password if the keystore only contains one key, which is how we suggest doing it.

As for the key's password... this is a classic ambiguity in current crypto recommendations. I'll spare you my standard rant for now, but I'm also happy to offer it to you if useful. My suggestion would be that the password adds no value if you're not sharing the key, and if you are sharing the key, do you really think the password you picked is solid enough to protect the key? If so, then you surely need to put it somewhere safe, because you surely can't remember it... in which case you have now opened a massive can of worms. Oops, I gave you 50% of the standard rant anyway.

… apps

codecov · 2020-06-28T04:21:20Z

Codecov Report

Merging #342 into master will increase coverage by 0.00%.
The diff coverage is 100.00%.

Impacted Files	Coverage Δ
src/briefcase/platforms/android/gradle.py	`90.80% <100.00%> (ø)`
src/briefcase/integrations/xcode.py	`93.33% <0.00%> (+0.15%)`	⬆️

freakboy3742

Looks good. I'm wary of making crypto-based recommendations, but your comments make sense to me, so I guess we can commit to that.

I've made a few tweaks for editorial voice, but otherwise this looks good to go!

In checking the details, I did notice that there's a new version of the Play Store Console in Beta... so I guess we're going to need to review this a few months :-(

Add initial publishing & code signing docs for Android

42efec2

paulproteus requested a review from freakboy3742 April 8, 2020 02:46

freakboy3742 requested changes Jun 14, 2020

View reviewed changes

Merge remote-tracking branch 'upstream/master' into add-code-signing-…

861d230

…and-publishing-docs-android

paulproteus force-pushed the add-code-signing-and-publishing-docs-android branch from c1d76c7 to 861d230 Compare June 26, 2020 23:29

paulproteus added 2 commits June 26, 2020 16:30

Revise code signing docs; use Android App Bundle

475498a

Add tabs to briefcase package invocation

94624a3

paulproteus changed the title ~~Add initial publishing & code signing docs for Android~~ Add publishing & signing docs; generate Android App Bundle Jun 26, 2020

paulproteus added 5 commits June 26, 2020 16:36

Say more about pixel size requirements

69c0161

Add changes file

7d60c17

Clarify that you have to jump all over the place

418f4b3

Change *package* command (and unchange accidentally-changed *build* c…

9f28207

…ommand)

Your app metadata may be helpful here.

c6fd549

paulproteus marked this pull request as ready for review June 27, 2020 00:21

paulproteus requested a review from freakboy3742 June 27, 2020 00:22

freakboy3742 reviewed Jun 27, 2020

View reviewed changes

paulproteus and others added 5 commits June 26, 2020 17:56

Specify app name always, since briefcase project can contain multiple…

9636603

… apps

Updated release news snippets.

92d8560

Tweaked instructions for code signing.

cc2f24a

Tweaked Play Store publication docs.

8fb60e6

Docs markup tweak.

29fd936

freakboy3742 approved these changes Jun 28, 2020

View reviewed changes

freakboy3742 merged commit b20f89d into beeware:master Jun 28, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add publishing & signing docs; generate Android App Bundle #342

Add publishing & signing docs; generate Android App Bundle #342

paulproteus commented Apr 8, 2020 •

edited by freakboy3742

paulproteus commented Apr 8, 2020

paulproteus commented Apr 8, 2020

freakboy3742 left a comment

freakboy3742 Jun 14, 2020

paulproteus Jun 26, 2020

freakboy3742 Jun 14, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 26, 2020

paulproteus Jun 26, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 26, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 26, 2020

paulproteus Jun 26, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 26, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 26, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 26, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 27, 2020

freakboy3742 Jun 14, 2020

paulproteus Jun 27, 2020

paulproteus commented Jun 14, 2020

paulproteus commented Jun 27, 2020

freakboy3742 left a comment

freakboy3742 Jun 27, 2020

paulproteus Jun 27, 2020

paulproteus Jun 27, 2020

freakboy3742 Jun 27, 2020

paulproteus Jun 27, 2020

codecov bot commented Jun 28, 2020

freakboy3742 left a comment


		Run this command::

		$ keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias


		.. code-block:: bash

		$ ~/.briefcase/tools/java/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks android/*/app/build/outputs/bundle/release/app-release.aab upload-key -storepass android

Add publishing & signing docs; generate Android App Bundle #342

Add publishing & signing docs; generate Android App Bundle #342

Conversation

paulproteus commented Apr 8, 2020 • edited by freakboy3742

paulproteus commented Apr 8, 2020

paulproteus commented Apr 8, 2020

freakboy3742 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulproteus commented Jun 14, 2020

paulproteus commented Jun 27, 2020

freakboy3742 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Jun 28, 2020

Codecov Report

freakboy3742 left a comment

Choose a reason for hiding this comment

paulproteus commented Apr 8, 2020 •

edited by freakboy3742